Add post about a stable version of JSON Schema #23
Conversation
There was a problem hiding this comment.
I'm excited to see a post like this go out soon! However, a number of things come to mind for me when I read this.
- Don't bother explaining about the IETF and the history of the "draft" label. You already justified that in the ADR, and you did a good job. Bringing it up here again will only cause the people who think the IETF can be made to work for us to talk about that more. We don't need more people talking about us and the IETF (or W3C, etc.). At most, this could include a link to the ADR for those who might have missed it.
- You reference JavaScript a lot, but not everyone is a JavaScript programmer, many JavaScript programmers don't know the change process for the language, and many who are not do have good feelings about JavaScript as a language or as an ecosystem. TBH, if I had not had to read the TC39 process recently, references to JavaScript would be more concerning than reassuring. If you discuss what things about JavaScript and the TC39 process are beneficial, and how they translate to JSON Schema, that will be much more reassuring. I noticed from several post-ADR discussions that the idea of a programming language being a reasonable source of JSON Schema process was not widely understood and was viewed skeptically.
- People will want to know how to propose new keywords. While we do not yet have the details from a formal SDLC, we know the basics: Implement ideas as vocabulary keywords, and we (JSON Schema) will define criteria for consideration of keywords that have seen some success and have a broad enough audience to warrant spec inclusion. You don't have to say that STAGE-1 requires two successful implementations, as that's too detailed. The number might change, the name of STAGE-1 might change. But the point is that we are shifting from "file an issue and maybe we'll do something about it" to "implement it and show us that it works."
|
@handrews, we seem to have different ideas about the audience and scope of the post. I think the problem with sharing the ADR was that the general public isn't the audience of an ADR, we are. This post is intended to be the public facing version of the decision to decouple from IETF. It covers that same topic, but it's aimed at typical users of JSON Schema who just want to know what these changes mean to them, not people who read ADRs. However, I completely understand your concerns about potentially reopening a tangent discussion that we don't necessarily want to reopen. My expectation is that since this post provides the big picture context that is missing from the ADR, we should end up with less focus on IETF and more attention on the direction decoupling from IETF enables for the future of JSON Schema. Since this post is really about the vision for the future of JSON Schema, I want to stick to vision and avoid going into details about mechanisms, so I think that talking about how new keywords will be proposed is out of scope. I expect that kind of thing to be covered in a future post. I'll do what I can to work in your feedback, but given our different ideas about the audience and scope of the post, how much I'm able to incorporate will probably be limited. |
|
@jdesrosiers I did not intend to imply that you need to explain the whole keyword process (although I realized while at the grocery store just now that I basically had said that and pulled this up to clarify, I'm sorry I was not able to catch that in time even though what I published earlier was the 2nd version of feedback I wrote up). |
The only thing I insist on is that the role of vocabularies and custom dialects not be minimized or described in a way that relegates it to a second-class feature. |
Absolutely. My intention was to reassure users that use custom dialects and vocabularies that these features weren't going away, but warn that they're still evolving. You seem to have gotten the opposite message. I'll do my best to reword to make it harder to misunderstand. |
Thanks, yes, what you wrote landed very differently with me. I have noticed this pattern- while I do understand that you're not trying to minimize vocabulary/dialect things, the way you tend to write about them feels that way. This is why I said I wanted to "discuss the messaging" (and then proceeded to overwhelm that point with details, unfortunately). I think part of the issue here is the terminology, which has not entirely settled. When you talk about "unstable" features, that is a big red flag in my book. But when I ask you specifics about how you think about STAGE-2 in particular, what you say tends to be more reassuring. Perhaps this will make more sense to me as the SDLC is formalized, but right now I'm sure I'm not the only person who reads "unstable" this way. It also really stands out when only one thing is singled out as "unstable." For this particular post, is it really necessary to talk about the stability of the vocabulary mechanism? Most people don't even know what that is. You're not discussing the stability of any other specific part. Really all that is needed is to explain that the lack of (BTW, if you are going to keep the IETF stuff, you should really mention the IETF media type registration- I noticed people got considerably more comfortable and less likely to push when they heard about that). |
|
I pushed a new draft. I thought a lot about your feedback about the IETF discussion. It occurred to me that most of it wasn't really relevant, so I cut out a lot of it. I tried to focus on the parts that relate to the journey of how we ended up deciding to change our process. I hope you feel better about the new version. I removed mention about TC39 because, you're right, people don't know what that is. I also tried to create separation between what people might think of JavaScript as a language and how JavaScript evolves highlighting that they successfully manage the kinds of challenges we are trying to manage. I tried my best to address the "messaging" concerns you had. Let me know if I missed the mark. Let me know if the wording changes about implementations makes sense. I'm not super happy with it, but I think it's a little less ambiguous. |
|
I'm happy. 👍 |
pages/posts/stability.md
Outdated
| * Implementations only need to support the latest release. A library that | ||
| supports the 2025 release will automatically support the 2023 and 2024 | ||
| releases. The older releases will no longer need to be maintained as distinct | ||
| versions. |
There was a problem hiding this comment.
I'm wondering, do we need to spell out that this is, from that point forward, not including all previous versions of JSON Schema?
It's implied when you mention 2023, but do we want to avoid people potentially missing that implication?
There was a problem hiding this comment.
Good point. That could be easily misinterpreted.
This post is to give people context about why IETF isn't working for us and the direction we're headed in the future. The intention is to address the apprehension and uncertainty that people have been expressing about the announcement that we are leaving IETF, but also serves as a teaser to get people excited about what's coming next.